Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add operation definition for spec 3.0 #1006

Open
wants to merge 7 commits into
base: master
Choose a base branch
from

Conversation

buehlefs
Copy link


title: "Add operation definition for spec 3.0"

This PR adds the operation definition from #993 to the spec document.

The second commit adds links to the new definition in other parts of the spec.
The third rewords the description of message objects to better align with the new definition of operations in the spec and adds links to the relevant definitions.


Related issue(s): #993

Previous PR: #998 (opened new PR because of merge conflicts after spec 3 release)


Copy link

Quality Gate Passed Quality Gate passed

Kudos, no new issues were introduced!

0 New issues
0 Security Hotspots
No data about Coverage
No data about Duplication

See analysis details on SonarCloud

spec/asyncapi.md Outdated
@@ -131,11 +131,14 @@ A sender is a type of application, that is sending [messages](#definitionsMessag
### <a name="definitionsReceiver"></a>Receiver
A receiver is a type of application that is receiving [messages](#definitionsMessage) from [channels](#definitionsChannel). A receiver MAY receive from multiple channels depending on the [server](#definitionsServer), protocol, and the use-case pattern. A receiver MAY forward a received message further without changing it. A receiver MAY act as a consumer and react to the message. A receiver MAY act as a processor that, for example, aggregates multiple messages in one and forwards them.

### <a name="definitionsOperation"></a>Operation
An operation describes a specific action an [application](#definitionsApplication) can take to interact with the message-driven API. Operations are performed by sending (or receiving) [messages](#definitionsMessage) to (or from) [channels](#definitionsChannel).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see this as the opposite. An Operation is an action the API/Application performs. For example, if the action is send, It means the application API defined in the current AsyncAPI document is sending a message.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would never say, that an API performs some operation, as the API is just the description of the interface that is implemented by some application. I am on the same side with the direction of send and receive. I could add something like "Operations are always described from the point of view of the application." to make it clearer in which direction send and receive take their effect. (I was hoping that the context of the first sentence would make this clear already.)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, you are right about the API term. However, I'm confused about the meaning of this sentence then:

a specific action an application can take to interact with the message-driven API

So you mean the application which defines the Application API through the AsyncAPI Document takes actions to interact, but with who?
I think the issue is more on the with the message-driven API part. Maybe with the users of it's API or similar will make it more clear?
I leave this for you so you can come up with a better alternative than me (for sure).

Copy link
Author

@buehlefs buehlefs Mar 22, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, this is the tricky part. An AsyncAPI spec can describe operations for "consumers" of an API or for "providers" of an API. Especially with async APIs it is not always clear if an application is a pure consumer or provider of the API. The spec intentionally allows to document both kinds of applications.

This has language for both applications but is potentially more confusing:

a specific action an application can take to interact with or implement part of the message-driven API.

Or we state explicitly with whom the application interacts:

a specific action an application can take to interact with other sender or receiver applications [through the message-driven API].

I understand that the message-driven API term is confusing as it does not have a clear definition. I think that we should have a definition for that term (at least in the context of an AsyncAPI file), but that is a separate issue.
The AsyncAPI document clearly defines some kind of API. I would suggest calling the sum of all operations a view of (or a part of) the message-driven API (or interface) of the application.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

An AsyncAPI spec can describe operations for "consumers" of an API or for "providers" of an API. Especially with async APIs it is not always clear if an application is a pure consumer or provider of the API. The spec intentionally allows to document both kinds of applications.

Since v3, this statement was added:

The AsyncAPI document SHOULD describe the operations an application performs.

Source: https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md?plain=1#L19

Wouldn't we just document from that point of view as the standard? Honest question.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree. I just wanted to point out that the application can have an operation sendLoginCredentials (I would call this application a consumer/client of an API) while another application will have receiveLoginCredentials as operation (providing the API). Both applications can be described in an AsyncAPI document.

The AsyncAPI document SHOULD describe the operations an application performs.

Wouldn't we just document from that point of view as the standard? Honest question.

If this is one of the core principles behind AsyncAPI, then we should make this more prominent. Currently, I feel that it is often unclear if an AsyncAPI document describes an API, an Application, a set of Channels/Operations, or even a system of multiple Applications. While this sentence addresses this confusion, it is not enough. Repeating this information in a definition for "AsyncAPI [document]" would help improve its visibility.

As for this PR: I am currently leaning towards the second option, as it concretely describes what an operation is used for without referencing an API.
I will make this change later today (and also update the toc):

Suggested change
An operation describes a specific action an [application](#definitionsApplication) can take to interact with the message-driven API. Operations are performed by sending (or receiving) [messages](#definitionsMessage) to (or from) [channels](#definitionsChannel).
An operation describes a specific action an [application](#definitionsApplication) can take to interact with other [sender](#definitionsSender) or [receiver](#definitionsReceiver) applications. Operations are performed by sending (or receiving) [messages](#definitionsMessage) to (or from) [channels](#definitionsChannel).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While this sentence addresses this confusion, it is not enough. Repeating this information in a definition for "AsyncAPI [document]" would help improve its visibility.

I can agree this is not be super cristal clear. I invite you to open a new issue so we can work on it; happy to push it forward.

The point is that it is a fact, one single AsyncAPI document should describe no more than one application. An exception to this, would be an AsyncAPI document with all definitions located under components. That would be considered as a "menu" of components, such as channels, servers, operations, which can be reused by those individual AsyncAPI documents. At the end, that file could be describing your broker.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I will probably open an issue for this once this PR is merged. I have updated this PR to my suggested change above.

There is one more case: Multiple AsyncAPI documents may be used to describe different APIs of the same application (e.g., public facing API vs. internal API). So it is not 1 to 1 for AsyncAPI document to application.

Copy link
Member

@smoya smoya Apr 18, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So it is not 1 to 1 for AsyncAPI document to application.

There is no limitation on the number of documents. We talk about 1:1 because it's the most common scenario. But it all depends on how you want to expose those AsyncAPI documents to the users.
AsyncAPI spec doesn't limit anything on that side.

Copy link
Member

@smoya smoya left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@buehlefs Sorry for the delay, but I just reviewed your PR and left a comment.
Thanks for your help!

@buehlefs buehlefs requested a review from GreenRover as a code owner April 10, 2024 20:24
@buehlefs buehlefs requested a review from smoya April 22, 2024 10:12
Copy link

Quality Gate Passed Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
No data about Coverage
No data about Duplication

See analysis details on SonarCloud

Copy link
Member

@smoya smoya left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM! 🚀🌔

I feel we had a nice discussion here BTW 💯

@smoya
Copy link
Member

smoya commented Apr 24, 2024

/ptal

@asyncapi-bot
Copy link
Contributor

@char0n @fmvilas @GreenRover @dalelane @derberg Please take a look at this PR. Thanks! 👋

Copy link

This pull request has been automatically marked as stale because it has not had recent activity 😴

It will be closed in 120 days if no further activity occurs. To unstale this pull request, add a comment with detailed explanation.

There can be many reasons why some specific pull request has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this pull request forward. Connect with us through one of many communication channels we established here.

Thank you for your patience ❤️

@github-actions github-actions bot added the stale label Aug 24, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants